.TH GSIMPLECAL 1 "2014\-12\-12"

.SH NAME
gsimplecal \- lightweight calendar applet


.SH SYNOPSIS
.B gsimplecal [\-h|\-\-help|\-v|\-\-version|next_month|prev_month]


.SH DESCRIPTION
This manual page documents the usage of the
.B gsimplecal
command.

.PP
.B gsimplecal
is a lightweight calendar applet. When it is started, it first shows up, when
you run it again, it closes the running instance, thus making it very easy to
integrate anywhere without the need to make some wrapper scripts.

.PP
It was intentionally made for use with tint2 panel to be launched upon clock
click, but of course it will work with any other panel, or no panel at all. For
example you can bind it to some hotkey in you window manager config.

.PP
You may also configure
.B gsimplecal
to display different world time zones clocks. See the \fICONFIGURATION\fP
section for details.


.SH COMMANDS AND OPTIONS
.TP 5
\fB\-v, \-\-version\fP
Print the program name and version to stdout, then exit with code 0.

.TP 5
\fB\-h, \-\-help\fP
Print the short usage help to stderr, then exit with error code 2.

.TP 5
\fBprev_month, next_month\fP
If the program is not running, simply run it.
If the program is running, change currently displayed month.

.PP
If no options and commands are given, the program is toggled, i.e. if it is
running it stops, otherwise it starts.


.SH CONFIGURATION
.PP
To configure the application you should manually create the configuration file.
The file is first searched in
.nh
$XDG_CONFIG_HOME/gsimplecal/config.
Usually that will be
.nh
\fB~/.config/gsimplecal/config\fP.

If found, it is used. If not found, system-wide configuration is searched in
all the
.nh
\fB$XDG_CONFIG_DIRS/gsimplecal/config\fP
locations.

.SS Sample config file

.IP
show_calendar = 1
.br
show_timezones = 1
.br
mark_today = 1
.br
show_week_numbers = 0
.br
close_on_unfocus = 0
.br
external_viewer = sunbird \-showdate "%Y\-%m\-%d"
.br
clock_format = %a %d %b %H:%M
.br
force_lang = en_US.utf8
.br
mainwindow_decorated = 0
.br
mainwindow_keep_above = 1
.br
mainwindow_sticky = 0
.br
mainwindow_skip_taskbar = 1
.br
mainwindow_resizable = 0
.br
mainwindow_position = none
.br
mainwindow_xoffset = 0
.br
mainwindow_yoffset = 0
.br
clock_label = UTC
.br
clock_tz = :UTC
.br
clock_label = Local
.br
clock_tz = 

.SS Config options description

.PP
The options are pretty self explanatory, but here is detailed description:

.TP 5
\fBshow_calendar\fP: 1 or 0, defaults to 1.
Sets whether the calendar should be shown. Most users want this option to be 1.

.TP 5
\fBshow_timezones\fP: 1 or 0, defaults to 0.
Sets whether the different time zone clocks should be shown.

.TP 5
\fBmark_today\fP: 1 or 0, defaults to 1.
Sets whether today's date will be marked in the calendar (besides the default
selection, i.e. when you click on the other day, today will remain marked
somehow, e.g. in bold print).

.TP 5
\fBshow_week_numbers\fP: 1 or 0, defaults to 0.
Sets whether week numbers are shown in the calendar.

.TP 5
\fBclose_on_unfocus\fP: 1 or 0, defaults to 0.
Sets whether the calendar will close if the window loses focus. Note that if
mainwindow_skip_taskbar is set to 1 then the calendar window may not be given
focus upon creation

.TP 5
\fBexternal_viewer\fP: string, defaults to empty string.
Command line to run when doubleclicking a date. This string is strftime'd
(see \fIman strftime\fP for the possible substitutions)
and passed to the shell. Thus you can use pipes, redirections, and whatever,
I hope.
.br
Currently the shell is hardcoded to
.nh
/bin/sh
though. I hope that will do for all the users, but if you've got a trouble,
please file a ticket (see \fIREPORTING BUGS\fP).

.TP 5
\fBclock_format\fP: string
Sets the clocks format. Look \fIman strftime\fP for the possible formats.

.TP 5
\fBforce_lang\fP: string
Overrides the \fILANG\fP environment variable, thus making it possible to
change the first day of week, i.e. choose if Monday or Sunday goes first.
Basically it's the same as running gsimplecal as

    LANG=en_GB.utf8 gsimplecal

Must be one of \fIlocale \-a\fP output.

.TP 5
\fBmainwindow_decorated\fP: 1 or 0, defaults to 0.
Tells your window manager to decorate or not to decorate the main window.

.TP 5
\fBmainwindow_keep_above\fP: 1 or 0, defaults to 1.
Sets whether the main window should be placed on top of other windows by your
window manager.

.TP 5
\fBmainwindow_sticky\fP: 1 or 0, defaults to 0.
Tells your window manager to show gsimplecal on all desktops.

.TP 5
\fBmainwindow_skip_taskbar\fP: 1 or 0, defaults to 1.
Sets whether the main window should be shown in the task list by your panel or
window manager.

.TP 5
\fBmainwindow_resizable\fP: 1 or 0, defaults to 1.
Sets whether your window manager should allow the main window to be resized.
If you are using a tiling window manager which supports floating windows,
setting this options to 0 will most likely tell your WM not to tile the window.
(Tested with XMonad and Awesome).

.TP 5
\fBmainwindow_position\fP: mouse|center|none, defaults to mouse.
Tells your window manager where to place the gsimplecal window:
.TP 10
     \fBmouse\fP
.br
close to the mouse cursor position (this one is useful when you bind gsimplecal
on some mouse click command);
.TP 10
     \fBcenter\fP
.br
in the center of the screen;
.TP 10
     \fBnone\fP
.br
it's up to your window manager to decide, where to place the window
(this one is useful when you bind gsimplecal invocation on some hotkey, so you
can configure your window manager to place gsimplecal in some predefined
position).

.TP 5
\fBmainwindow_xoffset\fP and \fBmainwindow_yoffset\fP: integer, default to 0.
Allow for main window position fine tuning. Throw an integer at these, and
it'll move the window by that number of pixels.

.TP 5
\fBclock_label\fP and \fBclock_tz\fP: string
These two options should go in pairs and \fBmust\fP be in the order given.
.br
Each pair creates new clock. The clock_label variable sets the string to be
displayed near the clock, the clock_tz sets the time zone.
.br
If you omit the value for clock_tz, local time will be shown.
.br
For a list of time zones see \fIman timezone\fP, or \fIls /usr/share/zoneinfo\fP


.SH KEYBOARD ACCELERATORS
.PP
You may use the following keyboard accelerators while gsimplecal window has a
focus (not yet configurable):

.TP 5
\fBEscape\fP, \fBCtrl+w\fP, \fBCtrl+q\fP
Close the window.

.TP 5
\fBn\fP
Switch to the next month.

.TP 5
\fBp\fP
Switch to the previous month.

.TP 5
\fBN\fP
Jump one year forward.

.TP 5
\fBP\fP
Jump one year backward.

.TP 5
\fBhjkl\fP
Vi-style dates navigation:

\fBh\fP -> left

\fBj\fP -> down

\fBk\fP -> up

\fBl\fP -> right

.TP 5
\fBg\fP, \fBHome\fP
Jump to the current date.


.SH REPORTING BUGS
.PP
Please, report any issues to the gsimplecal issue tracker, available at:
.nh
https://github.com/dmedvinsky/gsimplecal/issues


.SH AUTHOR
Created by Dmitry Medvinsky et al.


.SH SEE ALSO
tzset(3),
strftime(3)
